package com.rcpcompany.ui.flows;

import org.eclipse.swt.graphics.Image;

/**
 * The interface of a flow director. A specific flow director is used to control
 * a specific screen flow made up of pages (specified as {@link IFlowPage
 * IFlowPages}).
 * 
 * @noimplement Extend AbstractFlowDirector
 * 
 * @author Tonny Madsen, The RCP Company
 */
public interface IFlowDirector {
	/**
	 * Returns the title of this director.
	 * <p>
	 * The title is used to name the view or dialog that shows this director.
	 * 
	 * @return the title
	 */
	public String getTitle();

	/**
	 * Returns the image to use for this director.
	 * <p>
	 * The image is used with the title.
	 * 
	 * @return the image
	 */
	public Image getImage();

	/**
	 * Opens this director.
	 * <p>
	 * This method should be used to specify:
	 * <ul>
	 * <li>additional buttons for this director using
	 * {@link IFlowContainer#addButton(String)}.</li>
	 * </ul>
	 * 
	 * @param container
	 *            the container of the director
	 */
	public void open(IFlowContainer container);

	/**
	 * Returns the container of this flow director.
	 * 
	 * @return the container
	 */
	public IFlowContainer getContainer();

	/**
	 * Disposes this director.
	 */
	public void dispose();

	/**
	 * Returns the current page of this director.
	 * 
	 * @return the current page
	 */
	public IFlowPage getCurrentPage();

	/**
	 * The possible values for {@link IFlowDirector#navigate(WhereTo)}.
	 */
	enum WhereTo {
		/**
		 * The directory to asked to go to the first step in the process.
		 */
		FIRST,

		/**
		 * The director is asked to go to the previous step in the process.
		 */
		PREVIOUS_STEP,

		/**
		 * The director is asked to go to the next step in the process.
		 */
		NEXT_STEP,

		/**
		 * The director is asked to finish the process.
		 * <p>
		 * May only be used when {@link IFlowDirector#canNavigate(WhereTo)}
		 * returns <code>true</code>.
		 */
		FINISH,

		/**
		 * The director is asked to cancel the process.
		 */
		CANCEL
	};

	/**
	 * Navigates the director according to the wanted destination.
	 * 
	 * @param where
	 *            the direction
	 */
	public void navigate(WhereTo where);

	/**
	 * Returns whether the director can navigate the flow at this point
	 * according to the specified direction.
	 * 
	 * @param where
	 *            the direction to test
	 * 
	 * @return <code>true</code> if the director can finish the flow at this
	 *         point
	 */
	public boolean canNavigate(WhereTo where);

	/**
	 * Returns whether a specific navigation button is wanted for this director.
	 * <p>
	 * Used to suppress specific standard buttons for a specific director.
	 * 
	 * @param where
	 *            the direction to test
	 * @return <code>true</code> if the button is wanted
	 */
	public boolean isNavigationButtonWanted(WhereTo where);

	/**
	 * Requests the director to update its internal state.
	 * <p>
	 * This method is called by pages whenever a state change is made in a page.
	 */
	public void updateState();
}
